The Datafile PD-CD 1 Issue 2

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 001 / _basicaof / DemoNotes

Wrap

Text File | 1994-10-26 | 25KB | 627 lines

=========================================================================== BasicAOF version 1.20 ⌐ Oregan Software Developments 1994 =========================================================================== NOTE: This demonstration version of BasicAOF can only process the supplied example files. This demo may be copied and given to others provided no charge is made and all the files are copied and are unaltered in any way. PD libraries may supply this demo as long as they do not charge more than ú2 for a single disc including P&P. BasicAOF is available now and costs ú34.95 inclusive from: Oregan Developments 36 Grosvenor Avenue Streetly : Sutton Coldfield B74 3PE Tel: 0121 353 6044 (Access/Visa) --------------------------------------------------------------------------- BasicAOF is a software development tool that enables Basic assembler to export ARM Object Format (AOF) files. These object files cannot be executed directly, but must first be linked using a linker. It is most efficient to construct larger and more complex programs from several object files, produced by BasicAOF and/or high level compilers (C, Pascal, Fortran etc) Mixing assembler and high level languages allows the construction of top quality programs because you can take advantage of the strong points of both worlds. For instance, writing most of the code in C allows you to exploit the portability of C, the maintainability of C and the power of C libraries and language. On the other hand, writing critical portions of code in Basic assembler allows you to exploit all the speed of ARM processor and access directly hardware or operating system. Basic assembler is very popular because it is inbuilt in RISC OS ROM and is interfaced with the BBC Basic interpreter in a way that allows for great versatility. BasicAOF enables Basic assembler to: Å be invoked in multi-tasking mode Å save ARM Object Format files Å export global-scope symbols Å import external symbols Å relocate position-dependent code automatically at link time Å debug from Basic environment, in-memory-assembled code using Desktop Debugger Tool (DDT) Å re-assemble AOF files produced from C compiler or other code generators using DsasmBAOF disassembler Combining Basic assembler and BasicAOF you can use all the features provided in conventional assemblers and more besides, as the Basic interpreter has greater flexibility: Å repetitive assembly Å macro assembly Å conditional assembly Å global and local label capability Å comprehensive expression handling (including floating point expressions) Å rich operator and function set (including indirection operators) Å save any section of memory as AOF Å encapsulation of any binary file in generated AOF (e.g you can load a spritefile and generate exported symbols for the address of each sprite, or load a template definition and create a relocatable AOF with symbols for each window) Å Implementation of code generators facility (e.g. create optimised code plotting a particular sprite) You can find all the above features demonstrated in the example programs supplied. References and terminology ========================== It is assumed that reader is familiar with the following topics: a) definition of APCS b) using Link DDE tool c) using Make/AMU DDE tools d) using DDT debugger e) using BBC Basic Assembler Topics a), b), c), d) are addressed in Desktop Development Environment User Guide published by Acorn Computers Ltd. Topics a), b), e) are addressed in Appendixes of RISC OS 2/3 Programmer's Reference Manual published by Acorn Computers Ltd. The following terms and abbreviations are often used in the text: AIF Application Image Format. Executable RISC OS applications produced by Link DDE tool. ALF Acorn Library Format. A collection of AOF files constructed from a set of AOF files by the LibFile DDE tool. AMU Acorn Make Utility DDE tool. It is a tool managing the construction of executable program images, modules and libraries. It avoids needless re-processing of unaltered source files and ensures consistent construction using operations and dependencies specified in a Makefile. AOF ARM Object Format. A code file format generated by BasicAOF, compilers and assemblers. APCS ARM Procedure Call Standard. This is a contract between two procedures, one calling the other. The called procedure needs to know which registers it can freely change without restoring them before returning, and the caller needs to know which registers it can rely on not being corrupted over a procedure call. Additionally both procedures need to know which registers contain input arguments and return arguments, and the arrangement of stack backtrace data. Writing assembly language procedures that obey APCS is the key to interworking C and assembler. DDE Desktop Development Environment. An extendable set of RISC OS Desktop tools for developing applications and relocatable modules, developed by Acorn Computers Ltd. DDT Desktop Debugging Tool. An advanced interactive aid to debugging programs written in compiled languages and/or ARM assembler. Libfile A library management DDE tool. It can be used to create and maintain library archives (ALF files). Link The ARM linker tool supplied as part of DDE. Link tool accepts a set of AOF and ALF files as input and produces an AIF executable or a Relocatable Module as output. Make An interactive DDE tool that aids the programmer in the construction and maintenance of Makefiles. Objasm ARM AOF assembler developed by Acorn Computers Ltd forming part of the Desktop Assembler product. RISC_OSLib A library supplied with Acorn's ANSI C compiler, designed to help program applications to run under the desktop. Loading BasicAOF ================ BasicAOF is compatible with RISC OS 2 and RISC OS 3 and needs SharedCLibrary module version 3.75 or later. When you double click the !BasicAOF icon, BasicAOF will be installed as a relocatable module. It is assumed you have already installed DDE on your system in order to be able to use linking and managed compilation facilities. Programmers who want to program only using BasicAOF without using any compiled language, at least should install Link tool and Make/AMU tool from DDE tools. BasicAOF has extremely low memory requirements. Resident program code and workspace consume less than 19Kb in module area and memory is dynamically allocated, so more memory will be used only if really needed. As a result it is quite usable on smaller machines (1 MB RAM and floppy disc) Using BasicAOF ============== There are many features in BasicAOF but it is not possible to document the program fully in these notes. BasicAOF provides several SWIs for use in Basic assembler programs. The calls that probably will be used more frequently are: SYS "BasicAOF_Export" SYS "BasicAOF_SaveAOF" You can also call some BasicAOF SWIs via assembler macros that call directly the appropriate SWIs. Such macros are: FNimport(symbol$) FNweak(symbol$) FNreloc(label%) FNdebug(address%) Let's demonstrate some of the above calls in a minimal example: REM >Prog1 DIM code% 1000, L%-1 FOR pass=8 TO 10 STEP 2:P%=code%:[OPT pass .beep MOV r0, #7 SWI "OS_WriteC" MOVS pc, r14 ]:NEXT To export this trivial procedure with name "beep_proc" we should append the following line in the end of the program: SYS "BasicAOF_Export", "beep_proc", beep However this statement does not actually save the AOF file, thus after exporting all the symbols we want, we should add the following line: SYS "BasicAOF_SaveAOF", code%, P% This call specifies the start address of code and the end address of code. If the Basic source resides in 's' directory, the resulting AOF file will be saved in 's.^.o' directory. The exported procedure "beep_proc" can now be called from other C or Assembler programs such as the one below: REM >Prog2 DIM code% 1000, L%-1 FOR pass=8 TO 10 STEP 2:P%=code%:[OPTpass .entry_address BL FNimport("beep_proc") SWI "OS_Exit" ]:NEXT SYS "BasicAOF_SaveAOF", code%, P%,,, entry_address END DEF FNimport(symbol$) IF (pass AND 2) SYS "BasicAOF_Import", symbol$, P% =0 Here we have used FNimport() macro to call the symbol that was exported from Prog1. We have also specified an entry address which is the execution address for the whole program contained in these two short source files. In order to obtain the final executable, we must run the programs s.Prog1 and s.Prog2 and then link the object files using the following command: Link -o !RunImage o.Prog1 o.Prog2 Please note that code or data contained in AOF files must be relocatable, because the linker will position the contents of object files at an arbitrary location in the final executable. Thus if the code contains position dependent data (absolute pointers etc), you can use FNreloc to provide automatic relocation at linking stage. Instead of writing 'DCD pointer%' write 'DCD FNreloc(pointer%)' in your code, where pointer% is a program-relative address. Working styles ============== Å Unmanaged Development If you want to assemble a Basic source in unmanaged development style, just double click on the Basic file to run it. The AOF file produced will be saved with the default filename described above. This style can offer the quickest way of constructing small and simple programs. Å Managed Development This working style makes use of Makefiles to manage the construction of your programs. The DDE tools Make and AMU can both execute the commands in a Makefile running other tools to perform the make job. The Make tool also constructs Makefiles for you, avoiding the need for you to understand their syntax, and making it quick and easy to do this. The main advantages of managed development are that no unnecessary reprocessing of unaltered program sources is performed and programs are constructed consistently even when run by different people on different systems. These advantages make managed development the best style for the development of larger programs with code split into several source files. In order to use BasicAOF through Make/AMU, the Basic assembler sources must reside in a directory named 's' inside your Work Directory. An Objasm command will be invoked from AMU that will be trapped if the source is a Basic file and this file will be executed. Otherwise Objasm will be called with identical arguments. As a result mixed processing of BasicAOF and Objasm assembler sources is enabled. In addition please note that in managed development style, the Basic assembler multitasks under the RISC OS desktop, allowing other tasks to proceed while it operates. DDT debugging ============= If you wish to debug your final executable program with the DDT debugger, Link tool must be invoked with Debug option selected. Executing a binary produced in the above way, or dragging it onto the DDT icon starts a debugging session on it. Of course debugging will be at machine level (i.e. displaying the current execution position on a disassembly of memory). All global-scope symbols exported with BasicAOF will be shown in the DDT disassembling window. If you want to add more local-scope symbols to aid debugging, use SWI BasicAOF_Keep. Also please note that SWI BasicAOF_Debug provides a direct call to DDT from Basic assembler without forcing you to link the final executable program. Consequently testing and debugging a Basic assembler routine is made much easier and faster. You can see example '!BasicDDT' to understand how BasicAOF_Debug is used via FNdebug(address%) macro. Making your own linkable libraries ================================== Linkable libraries (ALF files) are collections of many AOF files stored in one file. When presented to linker as an input file, the referenced object files within a library are linked onto the output executable, but those not needed are left out. A linkable library is therefore a recommended way of storing a selection of useful procedures for re-use in a number of programs. You may well find that this facility can save you a lot of time by avoiding continually 'reinventing the wheel'. You will need the Libfile DDE tool to construct and modify linkable libraries. You can collect object files produced with BasicAOF in libraries. If you want to interwork your routines with other compiled languages like C, they must obey APCS. Utilities ========= The full version of the package includes also DsasmBAOF, a typical non-interactive DDE tool that disassembles AOF files and generates BasicAOF assembler source files. The program uses all available information to construct the closest representation of the original source and handles automatically the following data contained in AOF file: Å Global and local symbol information Å Relocation directives (type 1 PC-relative & additive) Å Automatic handling of Bcc/BLcc instructions Å Automatic handling of instructions ADRcc Rx,label/LDRcc Rx,label Å Automatic generation of appropriate labels Å Automatic handling of ASCII literal strings Å Supports CODE, DATA and NOINIT areas. DEBUG areas are ignored. Å FPE instructions displayed as data and comments Å APCS-RISC OS register bindings used for displaying assembler output You can examine AOF files extracted from libraries like RISC_OSLib or AnsiLib. DsasmBAOF is also useful for converting C programs to Basic assembler, in order to optimise or modify the generated code. BasicAOF Examples ================= If you want to understand quickly how BasicAOF is used, you can study the supplied well-documented example programs. Please note that considerable effort has been expended to provide useful and non-trivial examples, to demonstrate all features of BasicAOF with C compiler or standalone. All examples are cases where ARM code is essential for speed or low-level reasons. If you want to re-build the example programs double click on the relevant Makefile inside each Work Directory. The following sections describe the interesting points demonstrated in example programs: Wave3d ====== This is the simplest example as far as BasicAOF is concerned. The program consists of three short assembler sources and a main C source. s.intsqr This is a leaf procedure (one that calls no other procedures) computing the square root of an unsigned 32 bit number. It has been thoroughly optimised because it is called more than 2500 times per frame. This is a typical example of a procedure that must be written in ARM assembler for efficiency reasons. s.blitlines A simple procedure clearing video ram extremely fast. C code can not achieve the speed obtained with ARM assembler, when reading or writing memory blocks. s.Sin In this example, floating point expressions and indirection operators are used to access memory directly, in order to construct a lookup table of fixed point Sine values. This particular example can't be written in a conventional assembler. The closest you can get, is to write a program to create a binary file that will be loaded at assembly/run time, a technique which does not fit well in the automatic process of managed compilation. UnSqueeze ========= s.call_unsq A low-level procedure obeying APCS that calls code which corrupts all 16 ARM registers. Such low-level operations can not be easily written in C, but are simple in assembly. Wallpaper ========= s.Wallpaper Here is demonstrated, how to develop and debug an assembler routine in Basic environment and then export it with BasicAOF. Developing and debugging code is much easier in Basic environment compared with a conventional assembler, because you don't have to modify the source file, invoke the assembler, link a routine that will supply parameters to the developed procedure and finally run the executable. Modify variable debug% and run the program to see the routine executed in Basic. In addition you can see how macro assembly and conditional assembly can be implemented in Basic assembler. Bases ===== s.Bases This is a simple multi-tasking RISC OS application, contained in a short Basic assembler source file. However all Wimp handling is performed calling functions from RISC_OSLib, a library developed in C by Acorn. All RISC_OSLib and SharedCLibrary functions are called via FNimport() macro. The only exported symbol is "main" which is the name of the entry function in any C program. Parallax ======== s.blitstripe This is a procedure obeying APCS which has 6 input arguments and here is demonstrated how to load 5th and 6th arguments from stack. Additionally FNreloc() macro is used to relocate an array of pointers. Repetitive assembly and macro assembly are used in this example too. Also please note that symbol "screenbase" exported in this source is not a function, but an integer variable that will be initialised in the C part of program. s.ShiftPic In this example, a spritefile is loaded in memory and three shifted copies are created. Subsequently the bitmap addresses of each sprite are exported. Using this technique you can encapsulate any binary file (optionally processing it in any way) within an AOF file that will be linked into the executable. This will allow you to include data, text, sprites, templates, drawfiles etc. inside the !RunImage file of your application. In addition you can use FNreloc() macro to convert any datafile containing pointers, into a relocatable AOF file that can be positioned by the linker anywhere in the final executable (for example Template files). Also please note that in '!Parallax.Makefile' we have established a dependency between 's.ShiftPic' assembler source and 'dat.Pictureæ sprite file. As a result, whenever the sprite file is altered, Make/AMU will re-assemble 's.ShiftPic'. Exiter ====== You can assemble a module from a set of source files, a link step being required to join the produced AOF files to form the usable relocatable module. Exiter is a relocatable module split into three assembler sources. C language is not used in this example. The separation of routines into separately assembled files has many advantages (e.g. better maintenance and debugging) . Additionally since DDT cannot be used to debug modules, it can be useful to link routines into test applications, debug them with DDT, then link them into the module. It is a good idea to construct a module with the module header and the small routines/data associated with it in one source file, to be linked with the other source files forming the body of the module. s.RM_Header This is a general module header which you can adjust to form the headers of other relocatable modules. This module header file must be linked so that it is placed first in the module binary. To do this you should use the following statement: SYS "BasicAOF_SaveAOF", code%, P%, "!!!Module$$Header",&2202 Provided that areas are sorted by type and name, a name beginning with '!' is placed before an alphabetic name, so the above call can be used to ensure first placing. The module header source needs to contain FNimport() macros making available any symbols referenced in the module body. In addition, the initialisation routine should call, before anything else, __RelocCode, a routine added by the linker which relocates any absolute references to symbols when the module is initialised. s.ModuleBody Main section of module, comprising of Start, Initialisation, Finalisation and Service handlers. s.Keyevent The useful part of module. You can easily alter this part in order to perform other tasks like screen grabbing, volume control etc. ColorBars ========= This is an example demonstrating some advanced uses of BasicAOF. It consists of five assembler sources and a main C part. It is interesting to note that AOF file C:o.stubs, which contains the vectors of SharedCLibrary functions, is not linked in the final executable. Instead a minimal Run-Time System Kernel is used to interface C with operating system. As a result this C program is self-contained and does not require SharedCLibary module or AnsiLib library. This can be very useful in some situations. s.miniRTSK This assembler source implements an absolutely minimal Run-Time System Kernel that must be initialised before C "main" function is entered. That's why an entry address is defined in this file, which will be the execution address for the whole program. First of all we have to setup stack pointer (sp) and stack limit (sl) registers, needed by C code. A simple descending non-extendable stack is initialised and an appropriate stack overflow procedure is defined. User may set the initial stack size by defining a global variable in C named "stack_size". However if this variable is not defined, a default stack size of 2Kb is set. In order to detect if user has defined stack_size variable, symbol is referenced with FNweak() macro. If you specify in C source a small stack size, stack overflow error will be raised. Another interesting point is that in order to find the end of code and data in the final executable, the predefined linker symbol "Image$$RW$$Limit" is referenced. During linking stage, Link will assign to this symbol the end address of read-write section of image. As a result all memory above this address will not be used so we can setup there our stack. You can find out more about Linker pre-defined symbols, in DDE User Guide in the chapter titled "Link". s.xswi This is a simple but fast SWI veneer, to interface C with operating system SWI calls. s.Border A procedure changing screen border colour by accessing directly VIDC registers in SVC processor mode. Of course such low-level operations must be written in assembler and not C. Please note that the border colour is used as a CPU-load indicator. s.blitline A solution to the problem of unique macro labels in Basic assembler. Local label capability is incorporated in some conventional assemblers, but with effective use of Basic interpreter, it can be implemented in Basic assembler too. s.RGBmask A very useful code generator example. In this example a sprite is loaded in memory and specially optimised code depending on the sprite shape, is generated and saved as an AOF file. In fact, using this technique you can implement simple compilers and code generators producing AOF files via BasicAOF. For example you can implement the CMHG (C Module Header Generator) using this technique. Finally note that whenever the sprite file is modified, the optimised code will be re-assembled, because we have established a Makefile dependency similar to the !Parallax example. BasicDDT ======== An example demonstrating how to call DDT interactive debugger from Basic environment to make debugging easier and faster. You should have loaded DDT before running this program. After running the program, DDT is entered and registers R0-R13 have the same values setup by Basic's CALL/USR statement, i.e. R0-R7 = A%-H%. In DDT you can singlestep instructions, set breakpoints or watchpoints, trace execution, change registers or memory contents, evaluate expressions etc. When the end of assembler routine is reached, you should choose Quit entry from DDT's menu to return back to Basic environment. Registers R0-R13 after quitting DDT, are identical to the values on exit from routine.